From 3edfdb997508312e42ff96e5585dafddc9f3e80e Mon Sep 17 00:00:00 2001 From: Xue Fuqiao Date: Thu, 27 Feb 2014 22:09:26 +0800 Subject: [PATCH] Document some changes about windows. * doc/lispref/windows.texi (Window Sizes): Document `window-size'. (Display Action Functions): Document `display-buffer-at-bottom'. (Window Configurations): Minor fixes. * doc/lispref/modes.texi (Header Lines): Document `window-header-line-height'. * doc/lispref/display.texi (Scroll Bars): Document `window-scroll-bar-width'. * etc/NEWS: Related markup. --- doc/lispref/ChangeLog | 8 ++++++++ doc/lispref/display.texi | 6 ++++++ doc/lispref/modes.texi | 9 +++++++++ doc/lispref/windows.texi | 35 +++++++++++++++++++++++++++++++---- etc/NEWS | 4 ++++ 5 files changed, 58 insertions(+), 4 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 993dce602a3..99a2986cebe 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,5 +1,13 @@ 2014-02-27 Xue Fuqiao + * windows.texi (Window Sizes): Document `window-size'. + (Display Action Functions): Document `display-buffer-at-bottom'. + (Window Configurations): Minor fixes. + + * modes.texi (Header Lines): Document `window-header-line-height'. + + * display.texi (Scroll Bars): Document `window-scroll-bar-width'. + * windows.texi (Window Sizes, Resizing Windows): Document some pixelwise window operations. diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 519d33f5844..496fbf87041 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -3849,6 +3849,12 @@ bar actually occupies. @var{horizontal-type} is not actually meaningful. @end defun +@defun window-scroll-bar-width &optional window +This function returns the width of @var{window}'s vertical scrollbar, +in pixels. @var{window} must be a live window. If @var{window} is +@code{nil} or omitted, it will be the selected window. +@end defun + If you don't specify these values for a window with @code{set-window-scroll-bars}, the buffer-local variables @code{scroll-bar-mode} and @code{scroll-bar-width} in the buffer being diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index df0dd1a58e0..e12d00a5b59 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -2221,6 +2221,15 @@ is the same as for @code{mode-line-format} (@pxref{Mode Line Data}). It is normally @code{nil}, so that ordinary buffers have no header line. @end defvar +The function @code{window-header-line-height} returns the height of +the header line: + +@defun window-header-line-height &optional window +Return the height of @var{window}'s header line, in pixels. +@var{window} must be a live window. If @var{window} is @code{nil} or +omitted, it will be the selected window. +@end defun + A window that is just one line tall never displays a header line. A window that is two lines tall cannot display both a mode line and a header line at once; if it has a mode line, then it does not display a diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 08d82f57a93..ea7856d6f7f 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -413,6 +413,22 @@ default font. Thus, if a window is displaying text with a different font or size, the reported height and width for that window may differ from the actual number of text lines or columns displayed within it. +@defun window-size &optional window horizontal pixelwise round +This function returns the height or width of @var{window}. +@var{window} must be a valid window. The default value of +@var{window} is the selected window. + +If @var{horizontal} is omitted or nil, return the total height of +@var{window}, in lines; otherwise return the total width in columns. + +The optional argument @var{pixelwise} means return size of +@var{window}, in pixels. + +The optional argument @var{round} is ignored if @var{pixelwise} is +non-@code{nil}. Otherwise it is handled as for +@code{window-total-height} and @code{window-total-width}. +@end defun + @cindex window height @cindex height of a window @cindex total height of a window @@ -2078,6 +2094,15 @@ specified by that entry will override any other window found by the methods above, even if that window never showed @var{buffer} before. @end defun +@defun display-buffer-at-bottom buffer alist +This function tries to display @var{buffer} in a window at the bottom +of the selected frame. + +This either splits the window at the bottom of the frame or the +frame's root window, or reuses an existing window at the bottom of the +selected frame. +@end defun + @defun display-buffer-use-some-window buffer alist This function tries to display @var{buffer} by choosing an existing window and displaying the buffer in that window. It can fail if all @@ -3533,6 +3558,7 @@ to clone the state of a frame into an arbitrary live window (@code{set-window-configuration} effectively clones the windows of a frame into the root window of that very frame only). +@cindex window state @defun window-state-get &optional window writable This function returns the state of @var{window} as a Lisp object. The argument @var{window} must be a valid window and defaults to the root @@ -3554,10 +3580,11 @@ written to disk and read back in another session. In either case, use the following function to restore the state of the window. @defun window-state-put state &optional window ignore -This function puts the window state @var{state} into @var{window}. The -argument @var{state} should be the state of a window returned by an -earlier invocation of @code{window-state-get}, see above. The optional -argument @var{window} must specify a valid window and defaults to the +This function puts the window state @var{state} into @var{window}. +The argument @var{state} should be the state of a window returned by +an earlier invocation of @code{window-state-get}, see above. The +optional argument @var{window} can be either a live window or an +internal window (@pxref{Windows and Frames}) and defaults to the selected one. If @var{window} is not live, it is replaced by a live window before putting @var{state} into it. diff --git a/etc/NEWS b/etc/NEWS index fd2f380944a..da19f9c534b 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -254,9 +254,11 @@ As a command, it was a special case of `C-x 2' (`split-window-below'), and as such superfluous. After being reimplemented in Lisp, its interactive form was mistakenly retained. ++++ *** The functions `window-size' and `window-total-size' now have an optional argument to return a rounded size value. ++++ *** `window-state-put' now allows to put a window state into internal windows too. @@ -266,10 +268,12 @@ Available only on X, this option allows to control over-scrolling using the scroll bar (i.e. dragging the thumb down even when the end of the buffer is visible). ++++ *** New basic action function `display-buffer-in-previous-window' has `display-buffer' display a buffer in a window previously showing that buffer. ++++ *** New basic action function `display-buffer-at-bottom' has `display-buffer' choose or make a window at the bottom of the selected frame. -- 2.30.2